<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>Support Logical Resources</title>
</head>
<body>
<table border="0" cellspacing="5" cellpadding="2" width="100%">
  <tbody>
    <tr>
      <td align="left" valign="top" bgcolor="#0080c0"> <b><font
 color="#ffffff" face="Arial,Helvetica"> Eclipse 3.1 - Plan item</font></b>
      </td>
    </tr>
  </tbody>
</table>
<h1>Support Logical Resources</h1>
This document outlines the state of the Eclipse Platform <strong>Support
Logical Resources</strong> plan item. Interested parties should review
this document and verify that their use cases are reflected in the
requirements then later that the solution provided satisfies their
needs. Feedback is strongly encouraged and may be provided on the
platform-team-dev mailing list or in the <a
 href="http://bugs.eclipse.org/bugs/show_bug.cgi?id=37723">bug report</a>
for this plan item.
<p class="MsoNormal">This is the plan item:</p>
<blockquote>
  <p>"<em>The Eclipse Platform supports a strong physical view of
projects, files, and folders in the workspace. However, there are many
situations where a physical view is not the most salient or useful for
many purposes. In some cases, multiple distinct objects happen to be
stored in a single file, like an archive. Conversely, in other cases,
something that is logically a single object is stored across multiple
files. This discrepancy between logical and physical creates problems
for common operations such as searching, comparing, and versioning,
which need to work in the physical realm. Eclipse should support some
way of mapping between a logical view and the physical organization of
files on disk.</em>"</p>
  <p>Last Modified: July 2nd, 2003<br>
  </p>
</blockquote>
<h1>Motivation</h1>
<p>By definition Eclipse supports logical resources. It's a "an open
extensible IDE for anything and nothing in particular". The
applications that are built with it can be tailored to a particular
problem domain and the workbench extensions can be used to provide
support for any logical model. What Eclipse really doesn't support is
integrating tools at the logical model. In order to integrate two
plugins into Eclipse either the two plugins have to know about each
other, or both plugins have to depend on some common plugin. While the
first option is satisfactory for a few cases, the second case is the
most common and the most problematic. To illustrate, the Eclipse SDK
contains several plugins that are based on the Resources plugin (e.g.
Team, Search, Compare, JDT). When an application is packaged based on
the SDK, because the plugins in the SDK are resource based that is the
common integration point between plug-ins.<br>
</p>
<p>As you will see later, even the users of the SDK (JDT+CVS+Resources)
can observe some of the problems associated with the lack of support
for logical resources and the implicit mapping to physical resources.
The lack of a logical integration point causes the co-existance of
plugins in Eclipse to be error prone for the user. The next sections
will examine the relationships between logical and physical resources
and outline the visible problems with Eclipse 3.0.</p>
<h2>Existing Bugs</h2>
<p>Bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=32582">32582</a>
logical to physical mapping problem , 1 model element = 2 Files problem<br>
Bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=3979">3979</a>
[CVS Decorator] show version info works incorrectly for sub packages
(1GFDIEB)<br>
</p>
<h2>Logical Resources Defined<br>
</h2>
<p>Whereas logical resources are elements of the application that model
the data/processes of a particular problem domain, the physical
resources are the file system resources (e.g. files and folders) into
which an application will eventually transform their application model
for storage. Applications that don't use file system resources are not
being considered as part of this plan item. For example, an application
that stores it's application data directly into a database.</p>
<p>The following table enumerates concrete examples of how logical and
physical resources are used in current applications integrated into
Eclipse.</p>
<p><a name="#table1"></a>Table 1: Example logical to physical uses</p>
<table width="100%" border="1">
  <tbody>
    <tr>
      <td width="23%">
      <div align="center"><strong>Relationships</strong></div>
      </td>
      <td width="77%">
      <div align="center"><strong>Examples</strong></div>
      </td>
    </tr>
    <tr>
      <td>
      <p>logical (1) &lt;-&gt; (*) physical</p>
      <p>one logical to many physical</p>
      </td>
      <td valign="top">
      <p><a name="#1a"></a>(<strong>1a</strong>) EJB maps to several
physical files: (WSAD + XDE Tester). This is the most common case we
have found. </p>
      <blockquote>
        <p>/src/org/app/bean.java<br>
/src/org/app/beanr.java<br>
/src/org/app/beanlocal.java</p>
      </blockquote>
      <p><em>Note: If one of the logical resource's files was deleted
who would remember that the file used to exist and is an outgoing
deletion or that there is an incoming addition to the logical resource?</em></p>
      <p><a name="#1b"></a>(<strong>1b</strong>) Composite Object
(logical) maps to several changed physical resources. (Rational XDE)</p>
      <p><em>Note</em>: <em>With 1 to many relationship there is
always the complication that arises if the logical element maps to
files in an other project? This would cause many problems in the
current Team plugin.</em></p>
      </td>
    </tr>
    <tr>
      <td>
      <p>logical (*) &lt;-&gt; (1) physical</p>
      <p>many logical to one physical</p>
      </td>
      <td valign="top">
      <p><a name="#2a"></a>(<strong>2a</strong>) Methods in a class map
to their containing class file. (JDT)</p>
      <p><a name="#2b"></a>(<strong>2b</strong>) Archive files (zip,
jar) can be seen as a logical and the contents of the archive all map
to the same physical.(JTD + all)</p>
      </td>
    </tr>
    <tr>
      <td>
      <p>logical (1) &lt;-&gt; (1) physical</p>
      <p>one logical to one physical</p>
      </td>
      <td valign="top">
      <p><a name="#3a"></a>(<strong>3a</strong>) A Java Package maps to
a folder but a package does not include sub folders (e.g. they are
shallow). (JDT)</p>
      <p><a name="#3b"></a>(<strong>3b</strong>) A UML class maps to a
file. For example, in a UML application a class could be stored in a
single file called 'x435dsds.umlclass'. The reason it's a logical is
that the user of the application will never be concerned about the
actual file name or even the folder it's stored in. (XDE)</p>
      </td>
    </tr>
  </tbody>
</table>
<h1>Complaints<br>
</h1>
<p>The following complaints are representative of bug reports and
requirements received from several Eclipse users and developers.<br>
</p>
<h2>Complaint 1: Not very adaptable</h2>
<p>Object contributions and decorators are key mechanisms for providing
rich integration between tools. Using object contributions and
adaptable objects, any plugin can provide actions and decorators that
will show in another plugin's view. </p>
<p>Since IResource is the lowest common integration class and is
strongly mapped to its physical storage as files and folders, the
integration point for actions and decorators cannot be the logical
types in the view. The actions will consequently use the adaptable type
from the selection to perform the action or the decorator the resource
from the getImage request.</p>
<p>Here is an example to illustrate the problem with the CVS plugin.
When running a CVS commit action in the packages view the action
doesn't know that the IFolder is a Java package and is a shallow
namespace. It will use the selection and traverse the selected
IContainer using IContainer.members() and commit all child resources.
This is the same when the CVS outgoing decorator is shown on a package.
It will reflect the deep outgoing state of the IContainer. This can
lead to unexpected behavior because the user expected the action to run
on the model that the action was displayed on.</p>
<p>Example object contribution for the CVS commit action:</p>
<pre>&lt;extension point="org.eclipse.ui.popupMenus"&gt;<br> &lt;objectContribution<br>  objectClass="org.eclipse.core.resources.IResource"<br>  adaptable="true"<br>  id="org.eclipse.team.ccvs.ui.IResourceContributions"&gt;<br> &lt;filter<br>  name="projectPersistentProperty"<br>  value="org.eclipse.team.core.repository=org.eclipse.team.cvs.core.cvsnature"&gt;<br> &lt;/filter&gt;<br> &lt;action<br>  label="Commit"<br>  tooltip="Commit resource to CVS repository"<br>  class="org.eclipse.team.internal.ccvs.ui.actions.CommitAction"<br>  menubarPath="team.main/group3"<br>  id="org.eclipse.team.ccvs.ui.commit"&gt;<br> &lt;/action&gt;<br> &lt;objectContribution&gt;<br>&lt;/extension&gt;<br></pre>
<p>Example code run in the commit action to calculate the resources to
commit:</p>
<pre>public static Object[] getSelectedAdaptables(ISelection selection)    {<br>  ArrayList result = null;<br>  if (!selection.isEmpty()) {<br>    result = new ArrayList();<br>    Iterator elements = ((IStructuredSelection) selection).iterator();<br>    while (elements.hasNext()) {<br>      Object adapter = getAdapter(elements.next(), IResource.class);<br>      if (c.isInstance(adapter)) {<br>        result.add(adapter);<br>      }<br>    }<br>   }<br>   if (result != null &amp;&amp; !result.isEmpty()) {<br>   return (Object[])result.toArray((Object[])Array.newInstance(IResource.class, result.size()));<br>  }<br>  return (Object[])Array.newInstance(IResource.class, 0);<br>}</pre>
<p>Example code for defining an IResource adaptable decorator:</p>
<pre>&lt;extension<br>  point="org.eclipse.ui.decorators"&gt;<br>    &lt;decorator objectClass="org.eclipse.core.resources.IResource"<br>     adaptable="true"<br>     label="%DecoratorStandard.name"<br>     state="false"<br>     lightweight= "true"<br>     quadrant = "BOTTOM_RIGHT"<br>     class="org.eclipse.team.internal.ccvs.ui.CVSLightweightDecorator"<br>     id="org.eclipse.team.cvs.ui.decorator"&gt;<br>    &lt;description&gt;<br>      %DecoratorStandard.desc<br>    &lt;/description&gt;<br>  &lt;/decorator&gt;<br>&lt;/extension&gt;</pre>
<h2>Complaint 2: Decorators</h2>
<p>When the CVS decorator decorates a logical container in a view, the
desire is to decorate parents with the dirty indicator if one or more
of their logical children are dirty. To do this properly, the decorator
would need to query the dirty status of each of the logical children of
the container. This can be a costly operation as each child may itself
be a logical container. We have optimized the dirty decoration by
caching folder dirty states. This optimization becomes far more
complicated with logical models where the caching must be based on this
alternate model (i.e. the state must be cached for each model).</p>
<p> In addition, often decorators rely on&nbsp;IResource change events
to re-calculate some new state. In the case of a logical elements
representing several physical resources there is no easy way of
associated a IResource change event to its files and the actual logical
element.</p>
<h2>Complaint 3: Presentation of mixed logical models<br>
</h2>
<p>It would be nice to see the Java logical view in the Synchronize
view, in the navigator, or in dialogs contributed by other plug-ins
besides JDT. However, the entries in these views
may not be IResources so an IResource independent mapping mechanism
would be required. A workaround for this problem is demonstrated by the
Search plug-in which allows for plug-ins to integrate with other tools
by contributing domain specific pages. JDT contributes a JDT search
page to the view and shows logical Java elements. This solution however
doesn't allow showing mixed logical models in the same widget, which is
required several presentations in the SDK such as the Synchronize View,
Navigator, Refactoring Preview, and many others.<br>
</p>
Also, if an action prompts the user, for example to add resources to
CVS, what icons and labels are used in the dialog? It would be nice to
show those that are most familiar to the user. <br>
<br>
There are two levels of logical model presentation:<br>
<ul>
  <li>Need for full access to a logical model that would allow building
a dynamic UI. This would include mapping from an IResource to a logical
element (Complex).<br>
  </li>
</ul>
<ul>
  <li>Need name and icon for a logical element to display in simple
dialogs (Simple).<br>
  </li>
</ul>
<h2>Complaint 4: Change Sets</h2>
<p>Consider a user's action as a logical change, for example, the user
renames a class using the JDT refactoring action. In the user's mind he
'renamed a class' and knows that there have been side effects to other
resources. Currently there is not way of capturing these logical
actions
and associating the set of affected resources. This problem manifests
itself more in tools where almost every change to the model has side
effects.</p>
<h2>Complaint 5: Participating in operations</h2>
Some logical models may want to participate and even restrict the kinds
of operations are
allowed on theirs files. For example, if a logical element is composed
of three files, the users should not be allowed to move, or delete them
individually. In essence, a way of vetoing or participating in all
resource refactorings for resources that are part of a logical model.<br>
<br>
The most obvious problem in the current Eclipse is that the resource
navigator exposes resource refactorings (move, delete, copy) and the
logical cannot easily override this behavior. <br>
<h2>Complaint 6: IResource based views in the IDE</h2>
There are several views in the workbench IDE that could be used by
logical models but are currently too tied to resources. For example,
the problems and tasks views have a resource column and works uniquely
on IResource markers. This means that if a logical model provides
problems and tasks the problems and tasks views cannot be used to show
the logical element instead of the file.<br>
<h2>Complaint 7: Merging can't consider all files related to a logical
element</h2>
When merging a logical element the repository may find a conflict in
one of the files that is part of the logical element. The repository
tool will typically fetch the revisions for the conflicting file so
that a comparison can be shown to the user. But since the repository
tool doesn't know that other files are part of the logical resource,
the comparison shown to the user doesn't have access to the correct
revisions of the other files. This is a problem because it then becomes
impossible to implement a comparison that has access to all the
revisions of the logical element's files.<br>
<h2>Complaint 8: Creating non-IResource projects that appear in the
navigator</h2>
Currently the Navigator displays the Resources plugin workspace and
thus only resource projects can be displayed. Many clients would like
to create projects that are not file based. The current workaround is
to provide access to the non-file based project via a custom view, but
better integration would occur if the navigator actually showed all
project types.<br>
<h1>Discussion</h1>
<p>Given the number of different complaints about logical resource
support indicates that this is indeed a large problem space. If we plan
on addressing any of the complaints for 3.1, we will have to scope the
solution to address a subset of the complaints. I propose the following
grouping of the complaints:<br>
</p>
<p><span style="font-weight: bold;">Adaptables: Related to providing a
richer adaptable interface between plug-ins<br>
</span>Complaint 1: Not very adaptable<br>
Complaint 2: Decorators<br>
Complaint 7: Merging can't consider files related to a logical element<br>
</p>
<p><span style="font-weight: bold;">Presentation of logical models:
Related to exposing a non-resource based data modeling framework</span><br>
Complaint 6: IResource based views in the IDE<br>
Complaint 3: Presentation of mixed logical models<br>
</p>
<span style="font-weight: bold;">Others</span><br>
Complaint 4: Change Sets<br>
Complaint 5: Participating in operations<br>
<p>A common discussion in the community is the idea
that the resources plug-in should be generalized to become this generic
model, but in reality it wasn't designed as such and although it
contains common model services such as eventing and threading, it was
explicitly designed to model the file system. Changes to the resources
plug-in would be a major breaking API change and not acceptable to the
community. <br>
</p>
<p>For 3.1 we will only address the Adaptables group of complaints. See
<a href="logical-physical-adaptables.html">Solution 1: Support Logical
Resources - Adaptables</a> for a discussion on a possible solution and
investigate possible solutions for Complaint 3 and 5.<br>
</p>
</body>
</html>
